From 86604d8e019e235b6355d77cf65bd894e2793d30 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 26 Feb 2021 16:11:44 -0500 Subject: [PATCH] nativedialog: Convert docs --- gtk/gtknativedialog.c | 151 +++++++++++++++++++++--------------------- 1 file changed, 77 insertions(+), 74 deletions(-) diff --git a/gtk/gtknativedialog.c b/gtk/gtknativedialog.c index 71cceb4f8c..972616905a 100644 --- a/gtk/gtknativedialog.c +++ b/gtk/gtknativedialog.c @@ -36,24 +36,22 @@ #include "gtklabel.h" /** - * SECTION:gtknativedialog - * @Short_description: Integrate with native dialogs - * @Title: GtkNativeDialog - * @See_also: #GtkFileChooserNative, #GtkDialog + * GtkNativeDialog: * - * Native dialogs are platform dialogs that don't use #GtkDialog or - * #GtkWindow. They are used in order to integrate better with a - * platform, by looking the same as other native applications and - * supporting platform specific features. + * Native dialogs are platform dialogs that don't use `GtkDialog`. * - * The #GtkDialog functions cannot be used on such objects, but we - * need a similar API in order to drive them. The #GtkNativeDialog + * They are used in order to integrate better with a platform, by + * looking the same as other native applications and supporting + * platform specific features. + * + * The [class@Gtk.Dialog] functions cannot be used on such objects, + * but we need a similar API in order to drive them. The `GtkNativeDialog` * object is an API that allows you to do this. It allows you to set * various common properties on the dialog, as well as show and hide - * it and get a #GtkNativeDialog::response signal when the user finished - * with the dialog. + * it and get a [signal@Gtk.NativeDialog::response] signal when the user + * finished with the dialog. * - * Note that unlike #GtkDialog, #GtkNativeDialog objects are not + * Note that unlike `GtkDialog`, `GtkNativeDialog` objects are not * toplevel widgets, and GTK does not keep them alive. It is your * responsibility to keep a reference until you are done with the * object. @@ -205,7 +203,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class) gobject_class->dispose = gtk_native_dialog_dispose; /** - * GtkNativeDialog:title: + * GtkNativeDialog:title: (attributes org.gtk.Property.get=gtk_native_dialog_get_title org.gtk.Property.set=gtk_native_dialog_set_title) * * The title of the dialog window */ @@ -217,7 +215,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class) GTK_PARAM_READWRITE); /** - * GtkNativeDialog:modal: + * GtkNativeDialog:modal: (attributes org.gtk.Property.get=gtk_native_dialog_get_modal org.gtk.Property.set=gtk_native_dialog_set_modal) * * Whether the window should be modal with respect to its transient parent. */ @@ -229,7 +227,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class) GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY); /** - * GtkNativeDialog:visible: + * GtkNativeDialog:visible: (attributes org.gtk.Property.get=gtk_native_dialog_get_visible) * * Whether the window is currently visible. */ @@ -241,7 +239,7 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class) GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY); /** - * GtkNativeDialog:transient-for: + * GtkNativeDialog:transient-for: (attributes org.gtk.Property.get=gtk_native_dialog_get_transient_for org.gtk.Property.set=gtk_native_dialog_set_transient_for) * * The transient parent of the dialog, or %NULL for none. */ @@ -263,8 +261,8 @@ gtk_native_dialog_class_init (GtkNativeDialogClass *class) * * When this is called the dialog has been hidden. * - * If you call gtk_native_dialog_hide() before the user responds to - * the dialog this signal will not be emitted. + * If you call [method@Gtk.NativeDialog.hide] before the user + * responds to the dialog this signal will not be emitted. */ native_signals[RESPONSE] = g_signal_new (I_("response"), @@ -284,15 +282,16 @@ gtk_native_dialog_init (GtkNativeDialog *self) /** * gtk_native_dialog_show: - * @self: a #GtkNativeDialog + * @self: a `GtkNativeDialog` + * + * Shows the dialog on the display. * - * Shows the dialog on the display, allowing the user to interact with - * it. When the user accepts the state of the dialog the dialog will - * be automatically hidden and the #GtkNativeDialog::response signal - * will be emitted. + * When the user accepts the state of the dialog the dialog will + * be automatically hidden and the [signal@Gtk.NativeDialog::response] + * signal will be emitted. * * Multiple calls while the dialog is visible will be ignored. - **/ + */ void gtk_native_dialog_show (GtkNativeDialog *self) { @@ -302,7 +301,7 @@ gtk_native_dialog_show (GtkNativeDialog *self) g_return_if_fail (GTK_IS_NATIVE_DIALOG (self)); if (priv->visible) - return; + return; klass = GTK_NATIVE_DIALOG_GET_CLASS (self); @@ -316,14 +315,16 @@ gtk_native_dialog_show (GtkNativeDialog *self) /** * gtk_native_dialog_hide: - * @self: a #GtkNativeDialog + * @self: a `GtkNativeDialog` * - * Hides the dialog if it is visilbe, aborting any interaction. Once this - * is called the #GtkNativeDialog::response signal will not be emitted - * until after the next call to gtk_native_dialog_show(). + * Hides the dialog if it is visible, aborting any interaction. + * + * Once this is called the [signal@Gtk.NativeDialog::response] signal + * will *not* be emitted until after the next call to + * [method@Gtk.NativeDialog.show]. * * If the dialog is not visible this does nothing. - **/ + */ void gtk_native_dialog_hide (GtkNativeDialog *self) { @@ -348,18 +349,20 @@ gtk_native_dialog_hide (GtkNativeDialog *self) /** * gtk_native_dialog_destroy: - * @self: a #GtkNativeDialog + * @self: a `GtkNativeDialog` * * Destroys a dialog. * * When a dialog is destroyed, it will break any references it holds - * to other objects. If it is visible it will be hidden and any underlying - * window system resources will be destroyed. + * to other objects. * - * Note that this does not release any reference to the object (as opposed to - * destroying a GtkWindow) because there is no reference from the windowing - * system to the #GtkNativeDialog. - **/ + * If it is visible it will be hidden and any underlying window system + * resources will be destroyed. + * + * Note that this does not release any reference to the object (as opposed + * to destroying a `GtkWindow`) because there is no reference from the + * windowing system to the `GtkNativeDialog`. + */ void gtk_native_dialog_destroy (GtkNativeDialog *self) { @@ -380,13 +383,13 @@ _gtk_native_dialog_emit_response (GtkNativeDialog *self, } /** - * gtk_native_dialog_get_visible: - * @self: a #GtkNativeDialog + * gtk_native_dialog_get_visible: (attributes org.gtk.Method.get_property=visible) + * @self: a `GtkNativeDialog` * * Determines whether the dialog is visible. * * Returns: %TRUE if the dialog is visible - **/ + */ gboolean gtk_native_dialog_get_visible (GtkNativeDialog *self) { @@ -398,17 +401,18 @@ gtk_native_dialog_get_visible (GtkNativeDialog *self) } /** - * gtk_native_dialog_set_modal: - * @self: a #GtkNativeDialog + * gtk_native_dialog_set_modal: (attributes org.gtk.Method.set_property=modal) + * @self: a `GtkNativeDialog` * @modal: whether the window is modal * - * Sets a dialog modal or non-modal. Modal dialogs prevent interaction - * with other windows in the same application. To keep modal dialogs - * on top of main application windows, use - * gtk_native_dialog_set_transient_for() to make the dialog transient for the - * parent; most [window managers][gtk-X11-arch] - * will then disallow lowering the dialog below the parent. - **/ + * Sets a dialog modal or non-modal. + * + * Modal dialogs prevent interaction with other windows in the same + * application. To keep modal dialogs on top of main application + * windows, use [method@Gtk.NativeDialog.set_transient_for] to make + * the dialog transient for the parent; most window managers will + * then disallow lowering the dialog below the parent. + */ void gtk_native_dialog_set_modal (GtkNativeDialog *self, gboolean modal) @@ -427,13 +431,13 @@ gtk_native_dialog_set_modal (GtkNativeDialog *self, } /** - * gtk_native_dialog_get_modal: - * @self: a #GtkNativeDialog + * gtk_native_dialog_get_modal: (attributes org.gtk.Method.get_property=modal) + * @self: a `GtkNativeDialog` * - * Returns whether the dialog is modal. See gtk_native_dialog_set_modal(). + * Returns whether the dialog is modal. * * Returns: %TRUE if the dialog is set to be modal - **/ + */ gboolean gtk_native_dialog_get_modal (GtkNativeDialog *self) { @@ -445,12 +449,12 @@ gtk_native_dialog_get_modal (GtkNativeDialog *self) } /** - * gtk_native_dialog_set_title: - * @self: a #GtkNativeDialog + * gtk_native_dialog_set_title: (attributes org.gtk.Method.set_property=title) + * @self: a `GtkNativeDialog` * @title: title of the dialog * - * Sets the title of the #GtkNativeDialog. - **/ + * Sets the title of the `GtkNativeDialog.` + */ void gtk_native_dialog_set_title (GtkNativeDialog *self, const char *title) @@ -466,15 +470,15 @@ gtk_native_dialog_set_title (GtkNativeDialog *self, } /** - * gtk_native_dialog_get_title: - * @self: a #GtkNativeDialog + * gtk_native_dialog_get_title: (attributes org.gtk.Method.get_property=title) + * @self: a `GtkNativeDialog` * - * Gets the title of the #GtkNativeDialog. + * Gets the title of the `GtkNativeDialog`. * * Returns: (nullable): the title of the dialog, or %NULL if none has * been set explicitly. The returned string is owned by the widget * and must not be modified or freed. - **/ + */ const char * gtk_native_dialog_get_title (GtkNativeDialog *self) { @@ -495,15 +499,15 @@ parent_destroyed (GtkWidget *parent, } /** - * gtk_native_dialog_set_transient_for: - * @self: a #GtkNativeDialog + * gtk_native_dialog_set_transient_for: (attributes org.gtk.Method.set_property=transient-for) + * @self: a `GtkNativeDialog` * @parent: (allow-none): parent window, or %NULL * * Dialog windows should be set transient for the main application - * window they were spawned from. This allows - * [window managers][gtk-X11-arch] to e.g. keep the - * dialog on top of the main window, or center the dialog over the - * main window. + * window they were spawned from. + * + * This allows window managers to e.g. keep the dialog on top of the + * main window, or center the dialog over the main window. * * Passing %NULL for @parent unsets the current transient window. */ @@ -530,15 +534,14 @@ gtk_native_dialog_set_transient_for (GtkNativeDialog *self, } /** - * gtk_native_dialog_get_transient_for: - * @self: a #GtkNativeDialog + * gtk_native_dialog_get_transient_for: (attributes org.gtk.Method.get_property=transient-for) + * @self: a `GtkNativeDialog` * - * Fetches the transient parent for this window. See - * gtk_native_dialog_set_transient_for(). + * Fetches the transient parent for this window. * * Returns: (nullable) (transfer none): the transient parent for this window, - * or %NULL if no transient parent has been set. - **/ + * or %NULL if no transient parent has been set. + */ GtkWindow * gtk_native_dialog_get_transient_for (GtkNativeDialog *self) { -- 2.30.2